From 645e67231e2bfe09bec5efea59041ef7f28e3bd8 Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Sat, 2 Dec 2017 00:18:07 +0100 Subject: [PATCH] gtkeventcontrollerscroll: Add some docs --- docs/reference/gtk/gtk4.types.in | 1 + gtk/gtkeventcontrollerscroll.c | 114 +++++++++++++++++++++++++++++++ gtk/gtkeventcontrollerscroll.h | 14 ++++ 3 files changed, 129 insertions(+) diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in index 5b496dbd09..b2aefccacd 100644 --- a/docs/reference/gtk/gtk4.types.in +++ b/docs/reference/gtk/gtk4.types.in @@ -54,6 +54,7 @@ gtk_entry_buffer_get_type gtk_entry_completion_get_type gtk_entry_get_type gtk_event_controller_get_type +gtk_event_controller_scroll_get_type gtk_expander_get_type gtk_file_chooser_button_get_type gtk_file_chooser_dialog_get_type diff --git a/gtk/gtkeventcontrollerscroll.c b/gtk/gtkeventcontrollerscroll.c index 407f254c8b..c9819efbb9 100644 --- a/gtk/gtkeventcontrollerscroll.c +++ b/gtk/gtkeventcontrollerscroll.c @@ -17,6 +17,47 @@ * Author(s): Carlos Garnacho */ +/** + * SECTION:gtkeventcontrollerscroll + * @Short_description: Event controller for scroll events + * @Title: GtkEventControllerScroll + * @See_also: #GtkEventController + * + * #GtkEventControllerScroll is an event controller meant to handle + * scroll events from mice and touchpads. It is capable of handling + * both discrete and continuous scroll events, abstracting them both + * on the #GtkEventControllerScroll::scroll signal (deltas in the + * discrete case are multiples of 1). + * + * In the case of continuous scroll events, #GtkEventControllerScroll + * encloses all #GtkEventControllerScroll::scroll events between two + * #GtkEventControllerScroll::scroll-begin and #GtkEventControllerScroll::scroll-end + * signals. + * + * The behavior of the event controller can be modified by the + * flags given at creation time, or modified at a later point through + * gtk_event_controller_scroll_set_flags() (e.g. because the scrolling + * conditions of the widget changed). + * + * The controller can be set up to emit motion for either/both vertical + * and horizontal scroll events through #GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, + * #GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and #GTK_EVENT_CONTROLLER_SCROLL_BOTH. + * If any axis is disabled, the respective #GtkEventControllerScroll::scroll + * delta will be 0. Vertical scroll events will be translated to horizontal + * motion for the devices incapable of horizontal scrolling. + * + * The event controller can also be forced to emit discrete events on all devices + * through #GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement + * discrete actions triggered through scroll events (e.g. switching across + * combobox options). + * + * The #GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the + * #GtkEventControllerScroll::decelerate signal, emitted at the end of scrolling + * with two X/Y velocity arguments that are consistent with the motion that + * was received. + * + * This object was added in 3.93. + **/ #include "config.h" #include "gtkintl.h" @@ -319,6 +360,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) controller_class->handle_event = gtk_event_controller_scroll_handle_event; + /** + * GtkEventControllerScroll:flags: + * + * The flags affecting event controller behavior + * + * Since: 3.93 + **/ pspecs[PROP_FLAGS] = g_param_spec_flags ("flags", P_("Flags"), @@ -328,6 +376,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + /** + * GtkEventControllerScroll::scroll-begin: + * @controller: The object that received the signal + * + * Signals that a new scrolling operation has begun. It will + * only be emitted on devices capable of it. + **/ signals[SCROLL_BEGIN] = g_signal_new (I_("scroll-begin"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -335,6 +390,15 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) 0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * GtkEventControllerScroll::scroll: + * @controller: The object that received the signal + * @dx: X delta + * @dy: Y delta + * + * Signals that the widget should scroll by the + * amount specified by @dx and @dy. + **/ signals[SCROLL] = g_signal_new (I_("scroll"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -342,6 +406,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) 0, NULL, NULL, _gtk_marshal_VOID__DOUBLE_DOUBLE, G_TYPE_NONE, 2, G_TYPE_DOUBLE, G_TYPE_DOUBLE); + /** + * GtkEventControllerScroll::scroll-end: + * @controller: The object that received the signal + * + * Signals that a new scrolling operation has finished. It will + * only be emitted on devices capable of it. + **/ signals[SCROLL_END] = g_signal_new (I_("scroll-end"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -349,6 +420,18 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) 0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkEventControllerScroll::decelerate: + * @controller: The object that received the signal + * @vel_x: X velocity + * @vel_y: Y velocity + * + * Emitted after scroll is finished if the #GTK_EVENT_CONTROLLER_SCROLL_KINETIC + * flag is set. @vel_x and @vel_y express the initial velocity that was + * imprinted by the scroll events. @vel_x and @vel_y are expressed in + * pixels/ms. + **/ signals[DECELERATE] = g_signal_new (I_("decelerate"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -367,6 +450,18 @@ gtk_event_controller_scroll_init (GtkEventControllerScroll *scroll) sizeof (ScrollHistoryElem)); } +/** + * gtk_event_controller_scroll_new: + * @widget: a #GtkWidget + * @flags: behavior flags + * + * Creates a new event controller that will handle scroll events + * for the given @widget. + * + * Returns: a new #GtkEventControllerScroll + * + * Since: 3.93 + **/ GtkEventController * gtk_event_controller_scroll_new (GtkWidget *widget, GtkEventControllerScrollFlags flags) @@ -379,6 +474,15 @@ gtk_event_controller_scroll_new (GtkWidget *widget, NULL); } +/** + * gtk_event_controller_scroll_set_flags: + * @scroll: a #GtkEventControllerScroll + * @flags: behavior flags + * + * Sets the flags conditioning scroll controller behavior. + * + * Since: 3.93 + **/ void gtk_event_controller_scroll_set_flags (GtkEventControllerScroll *scroll, GtkEventControllerScrollFlags flags) @@ -392,6 +496,16 @@ gtk_event_controller_scroll_set_flags (GtkEventControllerScroll *scroll, } } +/** + * gtk_event_controller_scroll_get_flags: + * @scroll: a #GtkEventControllerScroll + * + * Gets the flags conditioning the scroll controller behavior. + * + * Returns: the controller flags. + * + * Since: 3.93 + **/ GtkEventControllerScrollFlags gtk_event_controller_scroll_get_flags (GtkEventControllerScroll *scroll) { diff --git a/gtk/gtkeventcontrollerscroll.h b/gtk/gtkeventcontrollerscroll.h index bbbf32e93c..55295fe05c 100644 --- a/gtk/gtkeventcontrollerscroll.h +++ b/gtk/gtkeventcontrollerscroll.h @@ -39,6 +39,20 @@ G_BEGIN_DECLS typedef struct _GtkEventControllerScroll GtkEventControllerScroll; typedef struct _GtkEventControllerScrollClass GtkEventControllerScrollClass; +/** + * GtkEventControllerScrollFlags: + * @GTK_EVENT_CONTROLLER_SCROLL_NONE: Don't emit scroll. + * @GTK_EVENT_CONTROLLER_SCROLL_VERTICAL: Emit scroll with vertical deltas. + * @GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL: Emit scroll with horizontal deltas. + * @GTK_EVENT_CONTROLLER_SCROLL_DISCRETE: Only emit deltas that are multiples of 1. + * @GTK_EVENT_CONTROLLER_SCROLL_KINETIC: Emit #GtkEventControllerScroll::decelerate + * after continuous scroll finishes. + * @GTK_EVENT_CONTROLLER_SCROLL_BOTH_AXES: Emit scroll on both axes. + * + * Describes the behavior of a #GtkEventControllerScroll. + * + * Since: 3.93 + **/ typedef enum { GTK_EVENT_CONTROLLER_SCROLL_NONE = 0, GTK_EVENT_CONTROLLER_SCROLL_VERTICAL = 1 << 0, -- 2.30.2